<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<link rel="stylesheet" href="documentation.css" />
	<title> Dauphin Tutorial</title> 
</head>
<body>
<h1> Dauphin </h1> <h2> Drop-in front end to MySQL databases. </h2> <h3> <a href="index.html"> Introduction</a> | Tutorial | <a href="advanced.html">Advanced</a> </h3> <h4> First you need some data </h4> 
<p>
	If you don't have a suitable database to test on, there is a sample database (four <strong> .sql </strong> files) you can install in the "data" folder. 
</p>
<p>
	The main file, <strong>people.sql</strong>, contains a table with 101 names, addresses and phone numbers. 
</p>
<p>
	The other three contain supplementary data for more advanced features. 
</p>
<p>
	Create all four tables on your database, from the command line or with your admin tool, etc. 
</p>
<h4> Set up the configuration file </h4> 
<p>
The file <strong>database_config.cgi</strong> contains the details of the database and the username and password you're using. This username will of course need insert and update privileges for the database.
</p>
<p>Here's an example of the contents of the <strong>database_config.cgi</strong> file:</p>
<pre>
$config = {
    db       => 'my_database',
    username => 'my_username',
    password => 'foobar'
  }
</pre>
<p>That's all you need. Don't make this file executable, for security reasons.
</p>
<h4> Set up the CGI file which will run Dauphin </h4> 
<p>
The file, which we'll call <strong>people.cgi</strong>, contains all the details Dauphin needs to access your data. There are five required values for the new() function:
</p>
<ul>
<li><code>main_table</code>, the name of the table;
</li>
<li><code>config_file</code>, the location of the <strong>database_config.cgi</strong> file;
</li>
<li><code>key_field</code>, the name of the Primary Key field for the table;
</li>
<li><code>display_fields</code>, an array specifying which fields to display in List view
</li>
<li><code>search_fields</code>, an array specifying which fields to search in
</li>
</ul>
<p>
Then the function <code>$dauphin->run()</code> does everything else.
</p>

<p>
Two optional parameters to new are:
</p>
<ul>
<li><code>sort_field</code>, which field to sort by in List view (if not found, the first field named in <code>display_fields</code> will be used);
</li>
<li><code>per_page</code>, how many items to show per page in List view (if not found, defaults to ten).
</li>
</ul>
<p>Here's an example of the <strong>people.cgi</strong> file:</p>
<pre>
#!/usr/bin/perl
use lib 'module'; 
use Dauphin;
$dauphin = Dauphin->new(
    main_table     => 'people',
    key_field      => 'id',
    display_fields => [ 'firstname', 'lastname', 'phone','state' ],
    sort_field     => 'lastname',
    config_file    => 'database_config.cgi',
    search_fields => [ 'firstname', 'lastname' ],
);

$dauphin->run();
</pre>
<p>
Other things you can add to <code>new()</code> are <code>css_path</code> and <code>template_path</code>, if you want to keep those files in a different location, and <code>per_page</code>, which determines the number of items shown in List view.
</p>
<p>
The line <code>use lib 'module';</code> tells the script the default path to the folder with Dauphin.pm in it.
</p>
<p>
That's it. If you now make people.cgi executable, and go to its location in a browser, Dauphin should work and show you a List view of your database. If not, it should at least give you a helpful error message. If you don't get even that much, probably adding <code>use CGI::Carp qw(fatalsToBrowser);</code> to the top of <strong>people.cgi</strong> should be your next step.
</p>
<p>
If you only need to work directly with one database table, that's all you need to know. But there are more complex relationships you can establish. See the <a href="advanced.html">Advanced</a> section for details.
</p>
<h4>Another table to edit?</h4>
<p>
If you have a need to edit another table in the same database, just copy your <strong>people.cgi</strong> file and change the details. If you need to edit another table in a different database, you'll need a second <strong>database_config.cgi</strong> as well.
</p>
</body>
</html>
